<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Advanced usage - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.paginator.advanced.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.paginator.advanced.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.paginator.configuration.html">Configuration</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.paginator.html">Zend_Paginator</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.pdf.html">Zend_Pdf</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.paginator.advanced" class="section"><div class="info"><h1 class="title">Advanced usage</h1></div>
    

    <div class="section" id="zend.paginator.advanced.adapters"><div class="info"><h1 class="title">Custom data source adapters</h1></div>
        

        <p class="para">
            At some point you may run across a data type that is not covered by
            the packaged adapters. In this case, you will need to write your
            own.
        </p>

        <p class="para">
            To do so, you must implement
            <span class="classname">Zend_Paginator_Adapter_Interface</span>. There are two
            methods required to do this:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">count()</p>
            </li>

            <li class="listitem">
                <p class="para">getItems($offset, $itemCountPerPage)</p>
            </li>
        </ul>

        <p class="para">
            Additionally, you&#039;ll want to implement a constructor that takes
            your data source as a parameter and stores it as a protected or
            private property. How you wish to go about doing this
            specifically is up to you.
        </p>

        <p class="para">
            If you&#039;ve ever used the SPL interface <a href="http://www.php.net/~helly/php/ext/spl/interfaceCountable.html" class="link external">&raquo; Countable</a>,
            you&#039;re familiar with  <span class="methodname">count()</span>. As used with
            <span class="classname">Zend_Paginator</span>, this is the total number of items
            in the data collection.
            Additionally, the <span class="classname">Zend_Paginator</span> instance provides a method
             <span class="methodname">countAllItems()</span> that proxies to the adapter
             <span class="methodname">count()</span> method.
        </p>

        <p class="para">
            The  <span class="methodname">getItems()</span> method is only slightly more
            complicated. For this, your adapter is supplied with an offset and
            the number of items to display per page. You must return the
            appropriate slice of data. For an array, that would be:
        </p>

        <pre class="programlisting brush: php">
return array_slice($this-&gt;_array, $offset, $itemCountPerPage);
</pre>


        <p class="para">
            Take a look at the packaged adapters (all of which implement the
            <span class="classname">Zend_Paginator_Adapter_Interface</span>) for ideas of how you
            might go about implementing your own.
        </p>
    </div>

    <div class="section" id="zend.paginator.advanced.scrolling-styles"><div class="info"><h1 class="title">Custom scrolling styles</h1></div>
        

        <p class="para">
            Creating your own scrolling style requires that you implement
            <span class="classname">Zend_Paginator_ScrollingStyle_Interface</span>, which defines
            a single method,  <span class="methodname">getPages()</span>. Specifically,
        </p>

        <pre class="programlisting brush: php">
public function getPages(Zend_Paginator $paginator, $pageRange = null);
</pre>


        <p class="para">
            This method should calculate a lower and upper bound for page
            numbers within the range of so-called &quot;local&quot; pages (that is, pages
            that are nearby the current page).
        </p>

        <p class="para">
            Unless it extends another scrolling style (see
            <span class="classname">Zend_Paginator_ScrollingStyle_Elastic</span> for an example),
            your custom scrolling style will inevitably end with something
            similar to the following line of code:
        </p>

        <pre class="programlisting brush: php">
return $paginator-&gt;getPagesInRange($lowerBound, $upperBound);
</pre>


        <p class="para">
            There&#039;s nothing special about this call; it&#039;s merely a convenience
            method to check the validity of the lower and upper bound and
            return an array of the range to the paginator.
        </p>

        <p class="para">
            When you&#039;re ready to use your new scrolling style, you&#039;ll need to
            tell <span class="classname">Zend_Paginator</span> what directory to look in. To do
            that, do the following:
        </p>

        <pre class="programlisting brush: php">
$prefix = &#039;My_Paginator_ScrollingStyle&#039;;
$path   = &#039;My/Paginator/ScrollingStyle/&#039;;
Zend_Paginator::addScrollingStylePrefixPath($prefix, $path);
</pre>

    </div>

    <div class="section" id="zend.paginator.advanced.caching"><div class="info"><h1 class="title">Caching features</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Paginator</span> can be told to cache the data it has already
            passed on, preventing the adapter from fetching them each time they are used.
            To tell paginator to automatically cache the adapter&#039;s data, just pass to
            its  <span class="methodname">setCache()</span> method a <span class="classname">Zend_Cache_Core</span>
            instance.
        </p>

        <pre class="programlisting brush: php">
$paginator = Zend_Paginator::factory($someData);
$fO = array(&#039;lifetime&#039; =&gt; 3600, &#039;automatic_serialization&#039; =&gt; true);
$bO = array(&#039;cache_dir&#039;=&gt;&#039;/tmp&#039;);
$cache = Zend_cache::factory(&#039;Core&#039;, &#039;File&#039;, $fO, $bO);
Zend_Paginator::setCache($cache);
</pre>


        <p class="para">
            As far as <span class="classname">Zend_Paginator</span> has got a
            <span class="classname">Zend_Cache_Core</span> instance, data will be cached. Sometimes you
            would like not to cache data even if you already passed a cache instance. You should
            then use  <span class="methodname">setCacheEnable()</span> for that.
        </p>

        <pre class="programlisting brush: php">
$paginator = Zend_Paginator::factory($someData);
// $cache is a Zend_Cache_Core instance
Zend_Paginator::setCache($cache);
// ... later on the script
$paginator-&gt;setCacheEnable(false);
// cache is now disabled
</pre>


        <p class="para">
            When a cache is set, data are automatically stored in it and pulled out from
            it. It then can be useful to empty the cache manually. You can get this done by
            calling  <span class="methodname">clearPageItemCache($pageNumber)</span>.
            If you don&#039;t pass any parameter, the whole cache will be empty. You can optionally
            pass a parameter representing the page number to empty in the cache:
        </p>

        <pre class="programlisting brush: php">
$paginator = Zend_Paginator::factory($someData);
Zend_Paginator::setCache($cache);
$items = $paginator-&gt;getCurrentItems();
// page 1 is now in cache
$page3Items = $paginator-&gt;getItemsByPage(3);
// page 3 is now in cache

// clear the cache of the results for page 3
$paginator-&gt;clearPageItemCache(3);

// clear all the cache data
$paginator-&gt;clearPageItemCache();
</pre>


        <p class="para">
            Changing the item count per page will empty the whole cache
            as it would have become invalid:
        </p>

        <pre class="programlisting brush: php">
$paginator = Zend_Paginator::factory($someData);
Zend_Paginator::setCache($cache);
// fetch some items
$items = $paginator-&gt;getCurrentItems();

// all the cache data will be flushed:
$paginator-&gt;setItemCountPerPage(2);
</pre>


        <p class="para">
            It is also possible to see the data in cache and ask for them directly.
             <span class="methodname">getPageItemCache()</span> can be used for that:
        </p>

        <pre class="programlisting brush: php">
$paginator = Zend_Paginator::factory($someData);
$paginator-&gt;setItemCountPerPage(3);
Zend_Paginator::setCache($cache);

// fetch some items
$items = $paginator-&gt;getCurrentItems();
$otherItems = $paginator-&gt;getItemsPerPage(4);

// see the cached items as a two-dimension array:
var_dump($paginator-&gt;getPageItemCache());
</pre>

    </div>

    <div class="section" id="zend.paginator.advanced.aggregator"><div class="info"><h1 class="title">Zend_Paginator_AdapterAggregate Interface</h1></div>
        

        <p class="para">
            Depending on your application you might want to paginate objects, whose internal
            data-structure is equal to existing adapters, but you don&#039;t want to break up your
            encapsulation to allow access to this data. In other cases an object might be in a
            &quot;has-an adapter&quot; relationship, rather than the &quot;is-an adapter&quot; relationsship that
            <span class="classname">Zend_Paginator_Adapter_Abstract</span> promotes. For this cases you can
            use the <span class="classname">Zend_Paginator_AdapterAggregate</span> interface that behaves
            much like the <span class="classname">IteratorAggregate</span> interface of the
            <acronym class="acronym">PHP</acronym> SPL extension.
        </p>

        <pre class="programlisting brush: php">
interface Zend_Paginator_AdapterAggregate
{
    /**
     * Return a fully configured Paginator Adapter from this method.
     *
     * @return Zend_Paginator_Adapter_Abstract
     */
    public function getPaginatorAdapter();
}
</pre>


        <p class="para">
            The interface is fairly small and only expects you to return an instance of
            <span class="classname">Zend_Paginator_Adapter_Abstract</span>. An Adapter Aggregate instance is
            then recognized by both  <span class="methodname">Zend_Paginator::factory()</span> and the
            constructor of <span class="classname">Zend_Paginator</span> and handled accordingly.
        </p>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.paginator.configuration.html">Configuration</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.paginator.html">Zend_Paginator</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.pdf.html">Zend_Pdf</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.paginator.html">Zend_Paginator</a></li>
  <li><a href="zend.paginator.introduction.html">Introduction</a></li>
  <li><a href="zend.paginator.usage.html">Usage</a></li>
  <li><a href="zend.paginator.configuration.html">Configuration</a></li>
  <li class="active"><a href="zend.paginator.advanced.html">Advanced usage</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>